
<!DOCTYPE html
	PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<title>Your Customized Coding Standard</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
</head>
<body>


<h1>C++ Coding Standard for Mystic Lake Software</h1>
<h3>Entity Naming</h3>
<ul>
<li><a href="#nncase">
Names shall begin with an upper case letter,  shall be lower case and words shall begin with an upper case letter.</a>
<li><a href="#nvcase">
Variables shall begin with a lower case letter.</a>
<li><a href="#nmvcase">
Member variables shall begin with an upper case letter and words shall begin with an upper case letter.</a>
<li><a href="#nmvpre">
Member variables shall be prefixed with "m".</a>
<li><a href="#nfuncase">
Functions shall begin with a lower case letter.</a>
<li><a href="#netorpre">
Enumerators shall be prefixed with "e".</a>
<li><a href="#nmacrocase">
Macros shall be upper case and words shall be separated by underscore (_).</a>
</ul>
<h3>Names</h3>
<ul>
<li><a href="#NameSensible">
Use sensible, descriptive names.</a>
<li><a href="#NameEnglish">
Only use english names.</a>
<li><a href="#NameLength">
Variables with a large scope shall have long names, variables with a small scope can have short names.</a>
<li><a href="#UseNamespace">
Use namespaces for identifiers declared in different
modules</a>
<li><a href="#UseNamePrefix">
Use name prefixes for identifiers declared in different
modules</a>
</ul>
<h3>Indentation and Spacing</h3>
<ul>
<li><a href="#BracesExdented">
Braces shall follow "Exdented Style".</a>
<li><a href="#IndentLevel">
Braces shall be indented 4 columns to the right of the starting position of the enclosing statement or declaration.</a>
<li><a href="#BracesLoop">
Loop and conditional statements shall always have brace enclosed
sub-statements.</a>
<li><a href="#StmtPerLine">
Each statement shall be placed on a line on its own.</a>
<li><a href="#ObjectPerDecl">
Declare each variable in a separate declaration.</a>
<li><a href="#OperSpace">
All binary arithmetic, bitwise and assignment operators and the ternary
conditional operator (?:) shall be surrounded by spaces; the comma operator
shall be followed by a space but not preceded; all other operators shall
not be used with spaces.</a>
<li><a href="#LineLength">
Lines shall not exceed 120 characters.</a>
<li><a href="#TabsAvoid">
Do not use tabs.</a>
</ul>
<h3>Comments</h3>
<ul>
<li><a href="#CommentEnglish">
Comments shall be written in english</a>
<li><a href="#CommentC">
Comments shall use the C-style.</a>
<li><a href="#CommentCpp">
Comments shall use the C++-style.</a>
<li><a href="#CommentPlacement">
All comments shall be placed above the line the comment
describes, indented identically.</a>
<li><a href="#CommentClass">
Every class shall have a comment that describes its purpose.</a>
<li><a href="#CommentFunction">
Every function shall have a comment that describes its purpose.</a>
</ul>
<h3>Files</h3>
<ul>
<li><a href="#OneVisibleClass">
There shall only be one externally visible class defined in
each header file.</a>
<li><a href="#FileNameCase">
File name shall be treated as case sensitive.</a>
<li><a href="#CFileExt">
C source files shall have extension "<tt>.c</tt>".</a>
<li><a href="#CHeaderExt">
C header files shall have extension "<tt>.h</tt>".</a>
<li><a href="#CppFileExt">
C++ source files shall have extension "<tt>.cpp</tt>".</a>
<li><a href="#CppHeaderExt">
C++ header files shall have extension "<tt>.h</tt>".</a>
<li><a href="#CppInlineExt">
Inline definition files shall have extension "<tt>.inl</tt>".</a>
<li><a href="#HeaderIncludeGuard">
Header files must have include guards.</a>
<li><a href="#IncludeGuardName">
The name of the macro used in the include guard shall have the same name
as the file (excluding the extension) followed by the suffix "_H".</a>
<li><a href="#HeaderSelfContained">
Header files shall be self-contained</a>
<li><a href="#HeaderSystemUser">
System header files shall be included with <> and project
headers with "".</a>
<li><a href="#IncludeFirst">
Put <tt>#include</tt> directives at the top of files.</a>
<li><a href="#IncludeAbsoluteAvoid">
Do not use absolute directory names in <tt>#include</tt>
directives.</a>
<li><a href="#ProvideCopyright">
Each file must start with a copyright notice.</a>
<li><a href="#ProvideRevision">
Each file must contain a revision marker.</a>
</ul>
<h3>Declarations</h3>
<ul>
<li><a href="#FunctionParameterNames">
Provide names of parameters in function declarations.</a>
<li><a href="#FunctionPointerTypedef">
Use a typedef to define a pointer to a function.</a>
<li><a href="#ExceptionSpecificationAvoid">
Do not use exception specifications.</a>
<li><a href="#UseVirtual">
Declare inherited functions <tt>virtual</tt>.</a>
<li><a href="#GlobalVarAvoid">
Do not use global variables.</a>
<li><a href="#UsingDeclHeaderAvoid">
Do not use global using declarations and using directives in
headers.</a>
<li><a href="#UsingDirAvoid">
Do not use using directives.</a>
<li><a href="#AccessOrder">
The parts of a class definition must be <tt>public</tt>,
<tt>protected</tt> and <tt>private</tt>.</a>
<li><a href="#PrivateData">
Declare class data private.</a>
<li><a href="#StructAsPodOnly">
Only use the keyword <tt>struct</tt> for C-style structs.</a>
<li><a href="#PreferFunctionsNonMember">
Functions that can be implemented using public
interface of a class shall not be members.</a>
</ul>
<h3>Statements</h3>
<ul>
<li><a href="#GotoRecoveryOnly">
Only use gotos for error recovery.</a>
<li><a href="#BreakAvoid">
Do not use <tt>break</tt> in loops.</a>
<li><a href="#ContinueAvoid">
Do not use <tt>continue</tt> in loops.</a>
<li><a href="#FunctionOneExit">
Only have one return in a function</a>
<li><a href="#SwitchDefault">
All switch statements shall have a default label.</a>
<li><a href="#DoWhileAvoid">
Do not use <tt>do-while</tt> loops.</a>
</ul>
<h3>Other Typographical Issues</h3>
<ul>
<li><a href="#MacrosAvoid">
Avoid macros.</a>
<li><a href="#MagicNumberAvoid">
Do not use literal numbers other than 0 and 1.</a>
<li><a href="#AssertEncourage">
Use plenty of assertions.</a>
<li><a href="#NewCastOps">
Use the new cast operators.</a>
</ul>
<hr />
<h2>Entity Naming</h2>
<a name="nncase" />
<h3>Names shall begin with an upper case letter,  shall be lower case and words shall begin with an upper case letter.</h3>
<a name="nvcase" />
<h3>Variables shall begin with a lower case letter.</h3>
<a name="nmvcase" />
<h3>Member variables shall begin with an upper case letter and words shall begin with an upper case letter.</h3>
<a name="nmvpre" />
<h3>Member variables shall be prefixed with "m".</h3>
<a name="nfuncase" />
<h3>Functions shall begin with a lower case letter.</h3>
<a name="netorpre" />
<h3>Enumerators shall be prefixed with "e".</h3>
<a name="nmacrocase" />
<h3>Macros shall be upper case and words shall be separated by underscore (_).</h3>
<h2>Names</h2>
<a name="NameSensible" />
<h3>Use sensible, descriptive names.</h3>

Do not use short cryptic names or names based on internal jokes.
It shall be easy to type a name without looking up how it is spelt.
<p>
Exception: Loop variables and variables with a small scope (less 
than 20 lines) may have short names to save space if the purpose of 
that variable is obvious.

<a name="NameEnglish" />
<h3>Only use english names.</h3>

It is confusing when mixing languages for names.
English is the preferred language because of its spread in the
software market and because most libraries used already use english.

<a name="NameLength" />
<h3>Variables with a large scope shall have long names, variables with a small scope can have short names.</h3>

Scratch variables used for temporary storage or indices are best kept
short. 
A programmer reading such variables shall be able to assume that its
value is not used outside a few lines of code.
Common scratch variables for integers are <tt>i</tt>, <tt>j</tt>,
<tt>k</tt>, <tt>m</tt>, <tt>n</tt> and for characters <tt>c</tt> and
<tt>d</tt>.

<a name="UseNamespace" />
<h3>Use namespaces for identifiers declared in different
modules</h3>

This avoids name clashes.

<a name="UseNamePrefix" />
<h3>Use name prefixes for identifiers declared in different
modules</h3>

This avoids name clashes.

<h2>Indentation and Spacing</h2>
<a name="BracesExdented" />
<h3>Braces shall follow "Exdented Style".</h3>

The Exdented Bracing Style means that the curly brace pair are lined
up with the surrounding statement. Statements and declarations
between the braces are indented relative to the braces.

<a name="IndentLevel" />
<h3>Braces shall be indented 4 columns to the right of the starting position of the enclosing statement or declaration.</h3>

Example:
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>void f(int a)
{
    int i;
    if (a &gt; 0)
    {
        i = a;
    }
    else
    {
        i = a;
    }
}
</pre></td></tr></table>
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>class A
{
};
</pre></td></tr></table>


<a name="BracesLoop" />
<h3>Loop and conditional statements shall always have brace enclosed
sub-statements.</h3>

The code looks more consistent if all conditional and loop statements
have braces.
<p>
Even if there is only a single statement after the condition or loop
statement today, there might be a need for more code in the future.

<a name="StmtPerLine" />
<h3>Each statement shall be placed on a line on its own.</h3>

There is no need to make code compact.
Putting several statements on the same line only makes the code
cryptic to read.

<a name="ObjectPerDecl" />
<h3>Declare each variable in a separate declaration.</h3>

This makes it easier to see all variables.

It also avoids the problem of knowing which variables are pointers. 
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>int* p, i;
</pre></td></tr></table>
It is easy to forget that the star belongs to the declared name, not the type,
and look at this and say that the type is "pointer to int" and both
<tt>p</tt> and <tt>i</tt> are declared to this type.


<a name="OperSpace" />
<h3>All binary arithmetic, bitwise and assignment operators and the ternary
conditional operator (?:) shall be surrounded by spaces; the comma operator
shall be followed by a space but not preceded; all other operators shall
not be used with spaces.</h3>


<a name="LineLength" />
<h3>Lines shall not exceed 120 characters.</h3>

Even if your editor handles long lines, other people may have set up
their editors differently. 
Long lines in the code may also cause problems for other programs and
printers.

<a name="TabsAvoid" />
<h3>Do not use tabs.</h3>

Tabs make the source code difficult to read where different programs
treat the tabs differently. 
The same code can look very differently in different views.
<p>
Avoid using tabs in your source code to avoid this problem.
Use spaces instead.

<h2>Comments</h2>
<a name="CommentEnglish" />
<h3>Comments shall be written in english</h3>


<a name="CommentC" />
<h3>Comments shall use the C-style.</h3>

Be consistent and use the <tt>/* ... */</tt> style comments.

<a name="CommentCpp" />
<h3>Comments shall use the C++-style.</h3>

Be consistent and use the <tt>// ...</tt> style comments.

<a name="CommentPlacement" />
<h3>All comments shall be placed above the line the comment
describes, indented identically.</h3>

Being consistent on placement of comments removes any question on what
the comment refers to.

<a name="CommentClass" />
<h3>Every class shall have a comment that describes its purpose.</h3>


<a name="CommentFunction" />
<h3>Every function shall have a comment that describes its purpose.</h3>


<h2>Files</h2>
<a name="OneVisibleClass" />
<h3>There shall only be one externally visible class defined in
each header file.</h3>

Having as few declarations as possible in a header file reduces header
dependencies.
<p>
The header file shall have the same name as the class plus
extension <tt>h</tt>.
<p>
External non-member functions that belong to the class interface may
also be declared in the same header file.

<a name="FileNameCase" />
<h3>File name shall be treated as case sensitive.</h3>


<a name="CFileExt" />
<h3>C source files shall have extension "<tt>.c</tt>".</h3>


<a name="CHeaderExt" />
<h3>C header files shall have extension "<tt>.h</tt>".</h3>


<a name="CppFileExt" />
<h3>C++ source files shall have extension "<tt>.cpp</tt>".</h3>


<a name="CppHeaderExt" />
<h3>C++ header files shall have extension "<tt>.h</tt>".</h3>


<a name="CppInlineExt" />
<h3>Inline definition files shall have extension "<tt>.inl</tt>".</h3>


<a name="HeaderIncludeGuard" />
<h3>Header files must have include guards.</h3>

The include guard protects against the header file being included
multiple times.
<p>
Example:
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>#ifndef FILE_H
#define FILE_H
...
#endif
</pre></td></tr></table>

<a name="IncludeGuardName" />
<h3>The name of the macro used in the include guard shall have the same name
as the file (excluding the extension) followed by the suffix "_H".</h3>


<a name="HeaderSelfContained" />
<h3>Header files shall be self-contained</h3>

When a header is included, there shall not be a need to include any
other headers first.
<p>
A simple way to make sure that a header file does not have any dependencies
is to include it first in the corresponding source file.
Example:
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>/* foobar.h */

#include "foobar.h"
#include &lt;stdio.h&gt;

...
</pre></td></tr></table>

<a name="HeaderSystemUser" />
<h3>System header files shall be included with <> and project
headers with "".</h3>


<a name="IncludeFirst" />
<h3>Put <tt>#include</tt> directives at the top of files.</h3>

Having all <tt>#include</tt> directives in one place makes it easy to
find them.

<a name="IncludeAbsoluteAvoid" />
<h3>Do not use absolute directory names in <tt>#include</tt>
directives.</h3>

The directory structure may be different on other systems.

<a name="ProvideCopyright" />
<h3>Each file must start with a copyright notice.</h3>


<a name="ProvideRevision" />
<h3>Each file must contain a revision marker.</h3>


<h2>Declarations</h2>
<a name="FunctionParameterNames" />
<h3>Provide names of parameters in function declarations.</h3>

Parameter names are useful to document what the parameter is used for.
<p>
The parameter names shall be the same in all declarations and
definitions of the function.

<a name="FunctionPointerTypedef" />
<h3>Use a typedef to define a pointer to a function.</h3>

Pointers to functions have a strange syntax. 
The code becomes much clearer if you use a typedef for the pointer to
function type.
This typedef name can then be used to declare variables etc.
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>double sin(double arg);
typedef double (*TrigFunc)(double arg);

/* Usage examples */
TrigFunc myfunc = sin;
void callFunc(TrigFunc callback);
TrigFunc functable[10];
</pre></td></tr></table>

<a name="ExceptionSpecificationAvoid" />
<h3>Do not use exception specifications.</h3>

Exception specifications in C++ are not as useful as they look.
The compiler does not make the code more efficient.
On the contrary, the compiler has to insert code to check that called
functions do not violate the specified exception specification at runtime.

<a name="UseVirtual" />
<h3>Declare inherited functions <tt>virtual</tt>.</h3>

An inherited function is implicitly <tt>virtual</tt> if it is declared
<tt>virtual</tt> in the base class.
Repeat the <tt>virtual</tt> keyword when declaring an inherited
function in a derived class to make it clear that this function is
<tt>virtual</tt>.

<a name="GlobalVarAvoid" />
<h3>Do not use global variables.</h3>

Use singleton objects instead.
<p>

Global variables are initialised when the program starts whether it will
be used or not.

A singleton object is only initialised when the object is used the
first time.

<p>
If global variables are using other global variables for their
initialisation there may be a problem if the dependent variables
are not initialised yet.
The initialisation order of global variables in different object files
is not defined.

Singleton objects do not have this problem as the dependent object
will be initialised when it is used.
However, watch out for cyclic dependencies in singleton object initialisations.


<a name="UsingDeclHeaderAvoid" />
<h3>Do not use global using declarations and using directives in
headers.</h3>

Bringing in names from a namespace to the global namespace may cause
conflicts with other headers.
The author of a header does not know in which context the header is
used and should avoid polluting the global namespace.
Instead, only use using declarations in the source files.

<a name="UsingDirAvoid" />
<h3>Do not use using directives.</h3>

Bringing in names from a namespace can cause all sorts of problems
as the namespace might contain more names than you would expect.
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>#include &lt;iostream&gt;

// Bring in names from the std namespace.
using namespace std;

// Declaring an object with the same name as
// a function in the std namespace.
int dec(int);

void f()
{
    // Now we can use iostream names lazily.
    cout &lt;&lt; "Hello world." &lt;&lt; endl;
    
    // Error: Ambiguous reference to dec.
    cout &lt;&lt; "Decimal base is " &lt;&lt; dec &lt;&lt; endl;
}
</pre></td></tr></table>

<a name="AccessOrder" />
<h3>The parts of a class definition must be <tt>public</tt>,
<tt>protected</tt> and <tt>private</tt>.</h3>

This makes it easy to read the class definition as the <tt>public</tt>
interface is of interest to most readers.

<a name="PrivateData" />
<h3>Declare class data private.</h3>

Classes shall encapsulate their data and only provide access to this
data by member functions to ensure that data in class objects are
consistent.

<p>
The exception to the rule is C type <tt>struct</tt> that only contains
data members.


<a name="StructAsPodOnly" />
<h3>Only use the keyword <tt>struct</tt> for C-style structs.</h3>


<a name="PreferFunctionsNonMember" />
<h3>Functions that can be implemented using public
interface of a class shall not be members.</h3>

A class definition can be kept small and less prone to change if it
only defines the core functionality.
Any other functions that can be implemented with this minimal class
definition shall be implemented as non-member functions.
They are still seen as part of the interface of the class.
<p>
Example:
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>class T
{
    T operator+=(const T &amp; right);
};

T operator+(const T &amp; left, const T &amp; right)
{
    T temp(left);
    temp += right;
    return temp;
}
</pre></td></tr></table>

<h2>Statements</h2>
<a name="GotoRecoveryOnly" />
<h3>Only use gotos for error recovery.</h3>

Although gotos are considered bad and breaks structured coding, it
is sometimes useful for error recovery from deep within nested loops.
In these cases the goto shall only jump to a label below in the code
and only into an outer scope.

<a name="BreakAvoid" />
<h3>Do not use <tt>break</tt> in loops.</h3>

A <tt>break</tt> statement is a goto statement in disguise and makes
code less readable.
<p>
A <tt>break</tt> statement is still acceptable in <tt>switch</tt> statements.

<a name="ContinueAvoid" />
<h3>Do not use <tt>continue</tt> in loops.</h3>

A <tt>continue</tt> statement is a goto statement in disguise and makes
code less readable.

<a name="FunctionOneExit" />
<h3>Only have one return in a function</h3>

It is confusing when there are more than one return statement in a
function. 
<p>
Having only one exit point of a function makes it easy to have a
single place for post conditions and invariant check.
<p>
When debugging It is useful to have a single exit point of a function
where you can put a single breakpoint or trace output.
<p>
It is sometimes necessary to introduce a result variable to carry the
function return value to the end of the function.
This is an acceptable compromise for structured code.


<a name="SwitchDefault" />
<h3>All switch statements shall have a default label.</h3>

Even if there is no action for the default label, it shall be included
to show that the programmer has considered values not covered by case
labels.
If the case labels cover all possibilities, it is useful to put an
assertion there to document the fact that it is impossible to get
here.
An assertion also protects from a future situation where a new
possibility is introduced by mistake.

<a name="DoWhileAvoid" />
<h3>Do not use <tt>do-while</tt> loops.</h3>

<tt>do-while</tt> loops are less readable than ordinary while loops and for
loops since the conditional is at the bottom of the loop. 
The reader must scan the entire loop in order to understand the scope
of the loop.
<p>
In addition, do-while loops are not needed. 
Any do-while loop can easily be rewritten into a while loop or a for
loop.
Reducing the number of constructs used enhance readability.

<h2>Other Typographical Issues</h2>
<a name="MacrosAvoid" />
<h3>Avoid macros.</h3>

Most macros can be replaced by constants, enumerations or inline functions.
<p>
As macros are not part of the C++ language, they do not provide type
safety and debugger support.

<a name="MagicNumberAvoid" />
<h3>Do not use literal numbers other than 0 and 1.</h3>

Use constants instead of literal numbers to make the code consistent
and easy to maintain.
The name of the constant is also used to document the purpose of the number.

<a name="AssertEncourage" />
<h3>Use plenty of assertions.</h3>

Assertions are useful to verify pre-conditions, post-conditions and
any other conditions that should never happen.
Pre-conditions are useful to verify that functions are called with
valid arguments.
They are also useful as documentation of what argument value ranges a
function is designed to work with.

<p>
Assertions are macros that print error messages when the condition is
not met.
The macros are disabled in release mode and do not cost anything in
performance or used memory in the end product.
<p>
Example: This square root function is only designed to work with
positive numbers.
<table cellspacing=10 cellpadding=5><tr><td width=20></td><td bgcolor="eeeeee"><pre>#include &lt;assert.h&gt;

double sqrt(double x)
{
    // precondition: x is positive
    assert(x &gt; 0);
    double result;
    ...
    // postcondition: result^2 ~= x
    assert(abs(result*result-x)/x &lt; 1E-8) ;
}
</pre></td></tr></table>


<a name="NewCastOps" />
<h3>Use the new cast operators.</h3>

Use <tt>dynamic_cast</tt>, <tt>const_cast</tt>, <tt>reinterpret_cast</tt>
and <tt>static_cast</tt> instead of the traditional C cast notation.
These document better what is being performed.

<hr />
<i>Generated 2006-09-18 by <a href="http://www.rosvall.ie/CSG">Coding Standard Generator</a> version 1.13.</i>

</body>
</html>